.\" $Id: PAPI_num_counters.3,v 1.13 2004/10/04 02:16:28 jthomas Exp $
.TH PAPI_num_counters 3 "September, 2004" "PAPI Programmer's Reference" "PAPI"

.SH NAME
PAPI_num_counters \- PAPI High Level: return the number of hardware counters available on the system

.SH SYNOPSIS
.B C Interface
.nf
.B #include <papi.h>
.BI "int\ PAPI_num_counters(void);"
.fi
.B Fortran Interface
.nf
.B #include "fpapi.h"
.BI PAPIF_num_counters(C_INT\  number )
.fi

.SH DESCRIPTION
.LP
.B PAPI_num_counters(\|)
returns the optimal length of the values array for the
high level functions.  This value corresponds to the number of hardware
counters supported by the current substrate.
.B PAPI_num_counters()
initializes the library to
.B PAPI_HIGH_LEVEL_INITED
if necessary.

.SH RETURN VALUES
On success, this function returns the number of hardware counters available.
 On error, a negative error code is returned.

.SH ERRORS
.TP
.B "PAPI_EINVAL"
.I "papi.h"
is different from the version used to 
compile the PAPI library.
.TP
.B "PAPI_ENOMEM"
Insufficient memory to complete the operation.
.TP
.B "PAPI_ESYS"
A system or C library call failed inside PAPI, see the 
.I "errno"
variable.

.SH EXAMPLES

.nf
.if t .ft CW
  int num_hwcntrs;
  /*  The installation does not support PAPI */
  if ((num_hwcntrs = PAPI_num_counters()) < 0 )
    handle_error(1);

  /*  The installation supports PAPI, but has no counters */
  if ((num_hwcntrs = PAPI_num_counters()) == 0 )
    fprintf(stderr,"Info:: This machine does not provide hardware counters.\n");
.if t .ft P
.fi

.SH BUGS
If you don't call this function, your application could core dump.

.SH SEE ALSO
.BR PAPI "(3)," PAPIF "(3)"
